JBoss.orgCommunity Documentation

Appendix B. Setting the JBOSS_HOME Environment Variable

The JBoss Communications Platform (JBoss Communications) is built on top of the JBoss Enterprise Application Platform. You do not need to set the JBOSS_HOME environment variable to run any of the JBoss Communications Platform servers unless JBOSS_HOME is already set.

The best way to know for sure whether JBOSS_HOME was set previously or not is to perform a simple check which may save you time and frustration.

Checking to See If JBOSS_HOME is Set on Unix

At the command line, echo $JBOSS_HOME to see if it is currently defined in your environment:

~]$ echo $JBOSS_HOME

The JBoss Communications Platform and most JBoss Communications servers are built on top of the JBoss Enterprise Application Platform (JBoss Enterprise Application Platform). When the JBoss Communications Platform or JBoss Communications servers are built from source, then JBOSS_HOME must be set, because the JBoss Communications files are installed into (or “over top of” if you prefer) a clean JBoss Enterprise Application Platform installation, and the build process assumes that the location pointed to by the JBOSS_HOME environment variable at the time of building is the JBoss Enterprise Application Platform installation into which you want it to install the JBoss Communications files.

This guide does not detail building the JBoss Communications Platform or any JBoss Communications servers from source. It is nevertheless useful to understand the role played by JBoss AS and JBOSS_HOME in the JBoss Communications ecosystem.

The immediately-following section considers whether you need to set JBOSS_HOME at all and, if so, when. The subsequent sections detail how to set JBOSS_HOME on Unix and Windows

Important

Even if you fall into the category below of not needing to set JBOSS_HOME, you may want to for various reasons anyway. Also, even if you are instructed that you do not need to set JBOSS_HOME, it is good practice nonetheless to check and make sure that JBOSS_HOME actually isn't set or defined on your system for some reason. This can save you both time and frustration.

You DO NOT NEED to set JBOSS_HOME if...

You MUST set JBOSS_HOME if...

Naturally, if you installed the JBoss Communications Platform or one of the JBoss Communications server binary releases which do not bundle JBoss Enterprise Application Platform, yet requires it to run, then you should install before setting JBOSS_HOME or proceeding with anything else.

Setting the JBOSS_HOME Environment Variable on Unix

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

Setting JBOSS_HOME in your personal ~/.bashrc startup script carries the advantage of retaining effect over reboots. Each time you log in, the environment variable is sure to be set for you, as a user. On Unix, it is possible to set JBOSS_HOME as a system-wide environment variable, by defining it in /etc/bashrc, but this method is neither recommended nor detailed in these instructions.

Procedure B.1. To Set JBOSS_HOME on Unix...

  1. Open the ~/.bashrc startup script, which is a hidden file in your home directory, in a text editor, and insert the following line on its own line while substituting for the actual install location on your system:

    export JBOSS_HOME="/home/<username>/<path>/<to>/<install_directory>"
  2. Save and close the .bashrc startup script.

  3. You should source the .bashrc script to force your change to take effect, so that JBOSS_HOME becomes set for the current session[2].

    ~]$ source ~/.bashrc
  4. Finally, ensure that JBOSS_HOME is set in the current session, and actually points to the correct location:

    Note

    The command line usage below is based upon a binary installation of the JBoss Communications Platform. In this sample output, JBOSS_HOME has been set correctly to the topmost_directory of the JBoss Communications installation. Note that if you are installing one of the standalone JBoss Communications servers (with JBoss AS bundled!), then JBOSS_HOME would point to the topmost_directory of your server installation.

    ~]$ echo $JBOSS_HOME
    /home/silas/<path>/<to>/<install_directory>
Setting the JBOSS_HOME Environment Variable on Windows

The JBOSS_HOME environment variable must point to the directory which contains all of the files for the JBoss Communications Platform or individual JBoss Communications server that you installed. As another hint, this topmost directory contains a bin subdirectory.

For information on how to set environment variables in recent versions of Windows, refer to http://support.microsoft.com/kb/931715.



[2] Note that any other terminals which were opened prior to your having altered .bashrc will need to source ~/.bashrc as well should they require access to JBOSS_HOME.